package com.kun.companion.core.queue;

import com.kun.companion.core.queue.enums.EventPriorityEnum;

/**
 * 按钮事件接口
 * <p>
 * 定义按钮事件处理的核心规范，支持以下特性：
 * 1. 事件唯一标识生成
 * 2. 优先级控制
 * 3. 异常重试策略
 * 4. UI更新协调
 * 5. 重试次数追踪
 * </p>
 *
 * @author gzc
 * @since 2025/2/3
 **/
public interface ButtonEvent {

    /**
     * 生成事件唯一标识
     * <p>默认实现组合时间戳和对象哈希值保证唯一性</p>
     *
     * @return 格式："btn-时间戳-哈希值" 的字符串标识
     */
    default String eventId() {
        return "btn-" + System.currentTimeMillis() + "-" + hashCode();
    }

    /**
     * 获取事件处理优先级
     *
     * @return 默认NORMAL优先级，可重写为HIGH/IMMEDIATE等
     */
    default EventPriorityEnum priority() {
        return EventPriorityEnum.NORMAL;
    }

    /**
     * 执行事件核心逻辑
     *
     * @throws Exception 执行过程中可能抛出的任何异常
     */
    void execute() throws Exception;

    /**
     * 定义可重试的异常类型
     * <p>仅列表中的异常类型会触发重试机制</p>
     *
     * @return 可重试异常类数组，默认空数组（不重试）
     */
    default Class<? extends Exception>[] retryableExceptions() {
        return new Class[0];
    }

    /**
     * 判断是否需要更新UI
     * <p>用于协调UI线程更新操作</p>
     *
     * @return 默认true（需要UI更新）
     */
    default boolean requireUIUpdate() {
        return true;
    }

    /**
     * 重试次数累加
     * <p>由队列处理器在每次重试前调用</p>
     */
    default void incrementRetryCount() {
    }

    ;

    /**
     * 获取当前重试次数
     *
     * @return 默认实现返回0，具体实现应维护状态
     */
    default long getRetryCount() {
        return 0;
    }
}